home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / canvas.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  57.1 KB  |  1,495 lines

  1. '\"
  2. '\" Copyright 1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/canvas.man,v 1.10 92/07/31 10:37:43 ouster Exp $ SPRITE (Berkeley)
  11. '/"
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS canvas cmds
  189. .BS
  190. '\" Note:  do not modify the .SH NAME line immediately below!
  191. .SH NAME
  192. canvas \- Create and manipulate canvas widgets
  193. .SH SYNOPSIS
  194. \fBcanvas\fI \fIpathName \fR?\fIoptions\fR?
  195. .SH "STANDARD OPTIONS"
  196. .LP
  197. .nf
  198. .ta 4c 8c 12c
  199. \fBbackground\fR    \fBcursorBorderWidth\fR    \fBselectBackground\fR    \fByScrollCommand\fR
  200. \fBborderWidth\fR    \fBcursorOffTime\fR    \fBselectBorderWidth\fR
  201. \fBcursor\fR    \fBcursorOnTime\fR    \fBselectForeground\fR
  202. \fBcursorBackground\fR    \fBrelief\fR    \fBxScrollCommand\fR
  203. .fi
  204. .LP
  205. See the ``options'' manual entry for details on the standard options.
  206. .SH "WIDGET-SPECIFIC OPTIONS"
  207. .ta 4c
  208. .LP
  209. .nf
  210. Name:    \fBcloseEnough\fR
  211. Class:    \fBCloseEnough\fR
  212. Command-Line Switch:    \fB\-closeenough\fR
  213. .fi
  214. .IP
  215. Specifies a floating-point value indicating how close the mouse cursor
  216. must be to an item before it is considered to be ``inside'' the item.
  217. Defaults to 1.0.
  218. .LP
  219. .nf
  220. .VS
  221. Name:    \fBconfine\fR
  222. Class:    \fBConfine\fR
  223. Command-Line Switch:    \fB\-confine\fR
  224. .fi
  225. .IP
  226. Specifies a boolean value that indicates whether or not it should be
  227. allowable to set the canvas's view outside the region defined by the
  228. \fBscrollRegion\fR argument.
  229. Defaults to true, which means that the view will
  230. be constrained within the scroll region.
  231. .VE
  232. .LP
  233. .nf
  234. Name:    \fBheight\fR
  235. Class:    \fBHeight\fR
  236. Command-Line Switch:    \fB\-height\fR
  237. .fi
  238. .IP
  239. Specifies a desired window height that the canvas widget should request from
  240. its geometry manager.  The value may be specified in any
  241. of the forms described in the COORDINATES section below.
  242. .LP
  243. .nf
  244. Name:    \fBscrollIncrement\fR
  245. Class:    \fBScrollIncrement\fR
  246. Command-Line Switch:    \fB\-scrollincrement\fR
  247. .fi
  248. .IP
  249. Specifies a distance used as increment during scrolling:  when one of
  250. the arrow buttons on an associated scrollbar is pressed, the picture
  251. will shift by this distance.  The distance may be specified in any
  252. of the forms described in the COORDINATES section below.
  253. .LP
  254. .nf
  255. Name:    \fBscrollRegion\fR
  256. Class:    \fBScrollRegion\fR
  257. Command-Line Switch:    \fB\-scrollregion\fR
  258. .fi
  259. .IP
  260. Specifies a list with four coordinates describing the left, top, right, and
  261. bottom coordinates of a rectangular region.
  262. This region is used for scrolling purposes and is considered to be
  263. the boundary of the information in the canvas.
  264. Each of the coordinates may be specified
  265. in any of the forms given in the COORDINATES section below.
  266. .LP
  267. .nf
  268. Name:    \fBwidth\fR
  269. Class:    \fBwidth\fR
  270. Command-Line Switch:    \fB\-width\fR
  271. .fi
  272. .IP
  273. Specifies a desired window width that the canvas widget should request from
  274. its geometry manager.  The value may be specified in any
  275. of the forms described in the COORDINATES section below.
  276. .BE
  277.  
  278. .SH INTRODUCTION
  279. .PP
  280. The \fBcanvas\fR command creates a new window (given
  281. by the \fIpathName\fR argument) and makes it into a canvas widget.
  282. Additional options, described above, may be specified on the
  283. command line or in the option database
  284. to configure aspects of the canvas such as its colors and 3-D relief.
  285. The \fBcanvas\fR command returns its
  286. \fIpathName\fR argument.  At the time this command is invoked,
  287. there must not exist a window named \fIpathName\fR, but
  288. \fIpathName\fR's parent must exist.
  289. .PP
  290. Canvas widgets implement structured graphics.
  291. A canvas displays any number of \fIitems\fR, which may be things like
  292. rectangles, circles, lines, and text.
  293. Items may be manipulated (e.g. moved or re-colored) and commands may
  294. be associated with items in much the same way that the \fBbind\fR
  295. command allows commands to be bound to widgets.  For example,
  296. a particular command may be associated with the <Button-1> event
  297. so that the command is invoked whenever button 1 is pressed with
  298. the mouse cursor over an item.
  299. This means that items in a canvas can have behaviors defined by
  300. the Tcl scripts bound to them.
  301.  
  302. .SH "DISPLAY LIST"
  303. .PP
  304. The items in a canvas are ordered for purposes of display,
  305. with the first item in the display list being displayed
  306. first, followed by the next item in the list, and so on.
  307. Items later in the display list obscure those that are
  308. earlier in the display list and are sometimes referred to
  309. as being ``on top'' of earlier items.
  310. When a new item is created it is placed at the end of the
  311. display list, on top of everything else.
  312. Widget commands may be used to re-arrange the order of the
  313. display list.
  314.  
  315. .SH "ITEM IDS AND TAGS"
  316. .PP
  317. Items in a canvas widget may be named in either of two ways:
  318. by id or by tag.
  319. Each item has a unique identifying number which is assigned to
  320. that item when it is created.  The id of an item never changes
  321. and id numbers are never re-used within the lifetime of a
  322. canvas widget.
  323. .PP
  324. Each item may also have any number of \fItags\fR associated
  325. with it.  A tag is just a string of characters, and it may
  326. take any form except that of an integer.
  327. For example, ``x123'' is OK but ``123'' isn't.
  328. The same tag may be associated with many different items.
  329. This is commonly done to group items in various interesting
  330. ways;  for example, all selected items might be given the
  331. tag ``selected''.
  332. .PP
  333. The tag \fBall\fR is implicitly associated with every item
  334. in the canvas;  it may be used to invoke operations on
  335. all the items in the canvas.
  336. .PP
  337. The tag \fBcurrent\fR is managed automatically by Tk;
  338. it applies to the \fIcurrent item\fR, which is the
  339. topmost item whose drawn area covers the position of
  340. the mouse cursor.
  341. If the mouse is not in the canvas widget or is not over
  342. an item, then no item has the \fBcurrent\fR tag.
  343. .PP
  344. When specifying items in canvas widget commands, if the
  345. specifier is an integer then it is assumed to refer to
  346. the single item with that id.
  347. If the specifier is not an integer, then it is assumed to
  348. refer to all of the items in the canvas that have a tag
  349. matching the specifier.
  350. The symbol \fItagOrId\fR is used below to indicate that
  351. an argument specifies either an id that selects a single
  352. item or a tag that selects zero or more items.
  353. Some widget commands only operate on a single item at a
  354. time;  if \fItagOrId\fR is specified in a way that
  355. names multiple items, then the normal behavior is for
  356. the command to use the first (lowest) of these items in
  357. the display list that is suitable for the command.
  358. Exceptions are noted in the widget command descriptions
  359. below.
  360.  
  361. .SH "COORDINATES"
  362. .PP
  363. All coordinates related to canvases are stored as floating-point
  364. numbers.
  365. Coordinates and distances are specified in screen units,
  366. which are floating-point numbers optionally followed
  367. by one of several letters.
  368. If no letter is supplied then the distance is in pixels.
  369. If the letter is \fBm\fR then the distance is in millimeters on
  370. the screen;  if it is \fBc\fR then the distance is in centimeters;
  371. \fBi\fR means inches, and \fBp\fR means printers points (1/72 inch).
  372. Larger y-coordinates refer to points lower on the screen;  larger
  373. x-coordinates refer to points farther to the right.
  374.  
  375. .SH TRANSFORMATIONS
  376. .PP
  377. Normally the origin of the canvas coordinate system is at the
  378. upper-left corner of the window containing the canvas.
  379. It is possible to adjust the origin of the canvas
  380. coordinate system relative to the origin of the window using the
  381. \fBxview\fR and \fByview\fR widget commands;  this is typically used
  382. for scrolling.
  383. Canvases do not support scaling or rotation of the canvas coordinate
  384. system relative to the window coordinate system.
  385. .PP
  386. Indidividual items may be moved or scaled using widget commands
  387. described below, but they may not be rotated.
  388.  
  389. .SH "INDICES"
  390. .PP
  391. Text items support the notion of an \fIindex\fR for identifying
  392. particular positions within the item.
  393. Indices are used for commands such as inserting text, deleting
  394. a range of characters, and setting the cursor position.
  395. An index may be specified in any of a number of ways, and
  396. different types of items may support different forms for
  397. specifying indices.
  398. Text items support the following forms for an index;  if you
  399. define new types of text-like items, it would be advisable to
  400. support as many of these forms as practical.
  401. Note that it is possible to refer to the character just after
  402. the last one in the text item;  this is necessary for such
  403. tasks as inserting new text at the end of the item.
  404. .TP 10
  405. \fInumber\fR
  406. A decimal number giving the position of the desired character
  407. within the text item.
  408. 0 refers to the first character, 1 to the next character, and
  409. so on.
  410. A number less than 0 is treated as if it were zero, and a
  411. number greater than the length of the text item is treated
  412. as if it were equal to the length of the text item.
  413. .TP 10
  414. \fBcursor\fR
  415. Refers to the character just before which the insertion cursor
  416. is drawn in this item.
  417. .TP 10
  418. \fBend\fR
  419. Refers to the character just after the last one in the item
  420. (same as the number of characters in the item).
  421. .TP 10
  422. \fBsel.first\fR
  423. Refers to the first selected character in the item.
  424. If the selection isn't in this item then this form is illegal.
  425. .TP 10
  426. \fBsel.last\fR
  427. Refers to the last selected character in the item.
  428. If the selection isn't in this item then this form is illegal.
  429. .TP 10
  430. \fB@\fIx,y\fR
  431. Refers to the character at the point given by \fIx\fR and
  432. \fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate
  433. system of the canvas.
  434. If \fIx\fR and \fIy\fR lie outside the coordinates covered by the
  435. text item, then they refer to the first or last character in the
  436. line that is closest to the given point.
  437.  
  438. .SH "WIDGET COMMAND"
  439. .PP
  440. The \fBcanvas\fR command creates a new Tcl command whose
  441. name is \fIpathName\fR.  This
  442. command may be used to invoke various
  443. operations on the widget.  It has the following general form:
  444. .DS C
  445. \fIpathName option \fR?\fIarg arg ...\fR?
  446. .DE
  447. \fIOption\fR and the \fIarg\fRs
  448. determine the exact behavior of the command.
  449. The following widget commands are possible for canvas widgets:
  450. .TP
  451. \fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg arg ...\fR?
  452. For each item that meets the constraints specified by
  453. \fIsearchSpec\fR and the \fIarg\fRs, add
  454. \fItag\fR to the list of tags associated with the item if it
  455. isn't already present on that list.
  456. It is possible that no items will satisfy the constraints
  457. given by \fIsearchSpec and \fIarg\fRs, in which case the
  458. command has no effect.
  459. This command returns an empty string as result.
  460. \fISearchSpec\fR and \fIarg\fR's may take any of the following
  461. forms:
  462. .RS
  463. .TP
  464. \fBabove \fItagOrId\fR
  465. Selects the item just after (above) the one given by \fItagOrId\fR
  466. in the display list.
  467. If \fItagOrId\fR denotes more than one item, then the last (topmost)
  468. of these items in the display list is used.
  469. .TP
  470. \fBall\fR
  471. Selects all the items in the canvas.
  472. .TP
  473. \fBbelow \fItagOrId\fR
  474. Selects the item just before (below) the one given by \fItagOrId\fR
  475. in the display list.
  476. If \fItagOrId\fR denotes more than one item, then the first (lowest)
  477. of these items in the display list is used.
  478. .TP
  479. \fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR?
  480. Selects the item closest to the point given by \fIx\fR and \fIy\fR.
  481. If more than one item is at the same closest distance (e.g. two
  482. items overlap the point), then the top-most of these items (the
  483. last one in the display list) is used.
  484. If \fIhalo\fR is specified, then it must be a non-negative
  485. value.
  486. Any item closer than \fIhalo\fR to the point is considered to
  487. overlap it.
  488. The \fIstart\fR argument may be used to step circularly through
  489. all the closest items.
  490. If \fIstart\fR is specified, it names an item using a tag or id
  491. (if by tag, it selects the first item in the display list with
  492. the given tag).
  493. Instead of selecting the topmost closest item, this form will
  494. select the topmost closest item that is below \fIstart\fR in
  495. the display list;  if no such item exists, then the selection
  496. behaves as if the \fIstart\fR argument had not been specified.
  497. .TP
  498. \fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
  499. Selects all the items completely enclosed within the rectangular
  500. region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
  501. \fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be
  502. no greater than \fIy2\fR.
  503. .TP
  504. \fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
  505. Selects all the items that overlap or are enclosed within the
  506. rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR,
  507. and \fIy2\fR.
  508. \fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be
  509. no greater than \fIy2\fR.
  510. .TP
  511. \fBwithtag \fItagOrId\fR
  512. Selects all the items given by \fItagOrId\fR.
  513. .RE
  514. .TP
  515. \fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR?
  516. .VS
  517. Returns a list with four elements giving an approximate bounding box
  518. for all the items named by the \fItagOrId\fR arguments.
  519. The list has the form ``\fIx1 y1 x2 y2\fR'' such that the drawn
  520. areas of all the named elements are within the region bounded by
  521. \fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top,
  522. and \fIy2\fR on the bottom.
  523. The return value may overestimate the actual bounding box by
  524. a few pixels.
  525. If no items match any of the \fItagOrId\fR arguments then an
  526. empty string is returned.
  527. .VE
  528. .TP
  529. \fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR?
  530. This command associates \fIcommand\fR with all the items given by
  531. \fItagOrId\fR such that whenever the event sequence given by
  532. \fIsequence\fR occurs for one of the items the command will
  533. be invoked.
  534. This widget command is similar to the \fBbind\fR command except that
  535. it operates on items in a canvas rather than entire widgets.
  536. See the \fBbind\fR manual entry for complete details
  537. on the syntax of \fIsequence\fR and the substitutions performed
  538. on \fIcommand\fR before invoking it.
  539. If all arguments are specified then a new binding is created, replacing
  540. any existing binding for the same \fIsequence\fR and \fItagOrId\fR
  541. (if the first character of \fIcommand\fR is ``+'' then \fIcommand\fR
  542. augments an existing binding rather than replacing it).
  543. In this case the return value is an empty string.
  544. If \fIcommand\fR is omitted then the command returns the \fIcommand\fR
  545. associated with \fItagOrId\fR and \fIsequence\fR (an error occurs
  546. if there is no such binding).
  547. If both \fIcommand\fR and \fIsequence\fR are omitted then the command
  548. returns a list of all the sequences for which bindings have been
  549. defined for \fItagOrId\fR.
  550. .RS
  551. .LP
  552. The only events for which bindings may be specified are those related
  553. to the mouse and keyboard, such as \fBEnter\fR, \fBLeave\fR,
  554. \fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR.
  555. The handling of events in canvases uses the current item defined
  556. in ITEM IDS AND TAGS above.
  557. \fBEnter\fR and \fBLeave\fR events trigger for an item when it
  558. becomes the current item or ceases to be the current item;  note
  559. that these events are different than \fBEnter\fR and \fBLeave\fR
  560. events for windows.
  561. Mouse-related events are directed to the current item, if any.
  562. Keyboard-related events are directed to the focus item, if any
  563. (see the \fBfocus\fR widget command below for more on this).
  564. .LP
  565. It is possible for multiple commands to be bound to a single
  566. event sequence for a single object.
  567. This occurs, for example, if one command is associated with the
  568. item's id and another is associated with one of the item's tags.
  569. When this occurs, the first matching binding is used.
  570. A binding for the item's id has highest priority, followed by
  571. the oldest tag for the item and proceeding through all of the
  572. item's tags up through the most-recently-added one.
  573. If a binding is associated with the tag \fBall\fR, the binding
  574. will have lower priority than all other bindings associated
  575. with the item.
  576. .RE
  577. .TP
  578. \fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR?
  579. Given a screen x-coordinate \fIscreenx\fR this command returns
  580. the canvas x-coordinate that is displayed at that location.
  581. If \fIgridspacing\fR is specfied, then the canvas coordinate is
  582. rounded to the nearest multiple of \fIgridspacing\fR units.
  583. .TP
  584. \fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR?
  585. Given a screen y-coordinate \fIscreeny\fR this command returns
  586. the canvas y-coordinate that is displayed at that location.
  587. If \fIgridspacing\fR is specfied, then the canvas coordinate is
  588. rounded to the nearest multiple of \fIgridspacing\fR units.
  589. .TP
  590. \fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
  591. Query or modify the configuration options of the widget.
  592. If no \fIoption\fR is specified, returns a list describing all of
  593. the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
  594. information on the format of this list).  If \fIoption\fR is specified
  595. with no \fIvalue\fR, then the command returns a list describing the
  596. one named option (this list will be identical to the corresponding
  597. sublist of the value returned if no \fIoption\fR is specified).  If
  598. one or more \fIoption\-value\fR pairs are specified, then the command
  599. modifies the given widget option(s) to have the given value(s);  in
  600. this case the command returns an empty string.
  601. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR
  602. command.
  603. .TP
  604. \fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR?
  605. .VS
  606. Query or modify the coordinates that define an item.
  607. If no coordinates are specified, this command returns a list
  608. whose elements are the coordinates of the item named by
  609. \fItagOrId\fR.
  610. If coordinates are specified, then they replace the current
  611. coordinates for the named item.
  612. If \fItagOrId\fR refers to multiple items, then
  613. the first one in the display list is used.
  614. .VE
  615. .TP
  616. \fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR?
  617. Create a new item in \fIpathName\fR of type \fItype\fR.
  618. The exact format of the arguments after \fBtype\fR depends
  619. on \fBtype\fR, but usually they consist of the coordinates for
  620. one or more points, followed by specifications for zero or
  621. more item options.
  622. See the subsections on individual item types below for more
  623. on the syntax of this command.
  624. This command returns the id for the new item.
  625. .TP
  626. \fIpathName \fBcursor \fItagOrId index\fR
  627. Set the position of the insertion cursor for the item(s)
  628. given by \fItagOrId\fR
  629. to just before the character whose position is given by \fIindex\fR.
  630. If some or all of the items given by \fItagOrId\fR don't support
  631. an insertion cursor then this command has no effect on them.
  632. See INDICES above for a description of the
  633. legal forms for \fIindex\fR.
  634. Note:  the insertion cursor is only displayed in an item if
  635. that item currently has the keyboard focus (see the widget
  636. command \fBfocus\fR, below), but the cursor position may
  637. be set even when the item doesn't have the focus.
  638. This command returns an empty string.
  639. .TP
  640. \fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR?
  641. For each item given by \fItagOrId\fR, delete the characters
  642. in the range given by \fIfirst\fR and \fIlast\fR,
  643. inclusive.
  644. If some of the items given by \fItagOrId\fR don't support
  645. text operations, then they are ignored.
  646. \fIFirst\fR and \fIlast\fR are indices of characters
  647. within the item(s) as described in INDICES above.
  648. If \fIlast\fR is omitted, it defaults to \fIfirst\fR.
  649. This command returns an empty string.
  650. .TP
  651. \fIpathName \fBdelete \fItagOrId\fR
  652. Delete each of the items given by \fItagOrId\fR, and return
  653. an empty string.
  654. .TP
  655. \fIpathName \fBdtag \fItagOrId \fR?tagToDelete\fR?
  656. For each of the items given by \fItagOrId\fR, delete the
  657. tag given by \fItagToDelete\fR from the list of those
  658. associated with the item.
  659. If an item doesn't have the tag \fItagToDelete\fR then
  660. the item is unaffected by the command.
  661. If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR.
  662. This command returns an empty string.
  663. .TP
  664. \fIpathName \fBfind \fIsearchCommand \fR?\fIarg arg ...\fR?
  665. This command returns a list consisting of all the items that
  666. meet the constraints specified by \fIsearchCommand\fR and
  667. \fIarg\fR's.
  668. \fISearchCommand\fR and \fIargs\fR have any of the forms
  669. accepted by the \fBaddtag\fR command.
  670. .TP
  671. \fIpathName \fBfocus \fR?\fItagOrId\fR?
  672. Set the keyboard focus for the canvas widget to the item given by
  673. \fItagOrId\fR.
  674. If \fItagOrId\fR refers to several items, then the focus is set
  675. to the first such item in the display list that supports the
  676. insertion cursor.
  677. If \fItagOrId\fR doesn't refer to any items, or if none of them
  678. support the insertion cursor, then the focus isn't changed.
  679. If \fItagOrId\fR is an empty
  680. string, then the focus item is reset so that no item has the focus.
  681. If \fItagOrId\fR is not specified then the command returns the
  682. id for the item that currently has the focus, or an empty string
  683. if no item has the focus.
  684. .RS
  685. .LP
  686. Once the focus has been set to an item, the item will display
  687. the insertion cursor and all keyboard events will be directed
  688. to that item.
  689. The focus item within a canvas and the focus window on the
  690. screen (set with the \fBfocus\fR command) are totally independent:
  691. a given item doesn't actually have the input focus unless (a)
  692. its canvas is the focus window and (b) the item is the focus item
  693. within the canvas.
  694. In most cases it is advisable to follow the \fBfocus\fR widget
  695. command with the \fBfocus\fR command to set the focus window to
  696. the canvas (if it wasn't there already).
  697. .TP
  698. \fIpathName \fBgettags\fR \fItagOrId\fR
  699. Return a list whose elements are the tags associated with the
  700. item given by \fItagOrId\fR.
  701. If \fItagOrId\fR refers to more than one item, then the tags
  702. are returned from the first such item in the display list.
  703. If \fItagOrId\fR doesn't refer to any items, or if the item
  704. contains no tags, then an empty string is returned.
  705. .RE
  706. .TP
  707. \fIpathName \fBindex \fItagOrId index\fR
  708. This command returns a decimal string giving the numerical index
  709. within \fItagOrId\fR corresponding to \fIindex\fR.
  710. \fIIndex\fR gives a textual description of the desired position
  711. as described in INDICES above.
  712. The return value is guaranteed to lie between 0 and the number
  713. of characters within the item, inclusive.
  714. If \fItagOrId\fR refers to multiple items, then the index
  715. is processed in the first of these items that supports indexing
  716. operations (in display list order).
  717. .TP
  718. \fIpathName \fBinsert \fItagOrId beforeThis string\fR
  719. For each of the items given by \fItagOrId\fR, if the item supports
  720. text insertion then \fIstring\fR is inserted into the item's
  721. text just before the character whose index is \fIbeforeThis\fR.
  722. See INDICES above for information about the forms allowed
  723. for \fIbeforeThis\fR.
  724. This command returns an empty string.
  725. .TP
  726. \fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
  727. This command is similar to the \fBconfigure\fR widget command except
  728. that it modifies item-specific options for the items given by
  729. \fItagOrId\fR instead of modifying options for the overall
  730. canvas widget.
  731. If no \fIoption\fR is specified, returns a list describing all of
  732. the available options for the first item given by \fItagOrId\fR
  733. (see \fBTk_ConfigureInfo\fR for
  734. information on the format of this list).  If \fIoption\fR is specified
  735. with no \fIvalue\fR, then the command returns a list describing the
  736. one named option (this list will be identical to the corresponding
  737. sublist of the value returned if no \fIoption\fR is specified).  If
  738. one or more \fIoption\-value\fR pairs are specified, then the command
  739. modifies the given widget option(s) to have the given value(s) in
  740. each of the items given by \fItagOrId\fR;  in
  741. this case the command returns an empty string.
  742. The \fIoption\fRs and \fIvalue\fRs are the same as those permissible
  743. in the \fBcreate\fR widget command when the item(s) were created;
  744. see the sections describing individual item types below for details
  745. on the legal options.
  746. .TP
  747. \fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR?
  748. Move all of the items given by \fItagOrId\fR to a new position
  749. in the display list just before the item given by \fIbelowThis\fR.
  750. If \fItagOrId\fR refers to more than one item then all are moved
  751. but the relative order of the moved items will not be changed.
  752. \fIBelowThis\fR is a tag or id;  if it refers to more than one
  753. item then the first (lowest) of these items in the display list is used
  754. as the destination location for the moved items.
  755. This command returns an empty string.
  756. .TP
  757. \fIpathName \fBmove \fItagOrId xAmount yAmount\fR
  758. Move each of the items given by \fItagOrId\fR in the canvas coordinate
  759. space by adding \fIxAmount\fR to the x-coordinate of each point
  760. associated with the item and \fIyAmount\fR to the y-coordinate of
  761. each point associated with the item.
  762. This command returns an empty string.
  763. .TP
  764. \fIpathName \fBraise \fItagOrId \fR?aboveThis\fR?
  765. Move all of the items given by \fItagOrId\fR to a new position
  766. in the display list just after the item given by \fIaboveThis\fR.
  767. If \fItagOrId\fR refers to more than one item then all are moved
  768. but the relative order of the moved items will not be changed.
  769. \fIAboveThis\fR is a tag or id;  if it refers to more than one
  770. item then the last (topmost) of these items in the display list is used
  771. as the destination location for the moved items.
  772. This command returns an empty string.
  773. .TP
  774. \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR
  775. Rescale all of the items given by \fItagOrId\fR in canvas coordinate
  776. space.
  777. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling
  778. operation and \fIxScale\fR and \fIyScale\fR identify the scale
  779. factors for x- and y-coordinates, respectively (a scale factor of
  780. 1.0 implies no change to that coordinate).
  781. For each of the points defining each item, the x-coordinate is
  782. adjusted to change the distance from \fIxOrigin\fR by a factor
  783. of \fIxScale\fR.
  784. Similarly, each y-coordinate is adjusted to change the distance
  785. from \fIyOrigin\fR by a factor of \fIyScale\fR.
  786. This command returns an empty string.
  787. .TP
  788. \fIpathName \fBscan\fR \fIoption args\fR
  789. This command is used to implement scanning on canvases.  It has
  790. two forms, depending on \fIoption\fR:
  791. .RS
  792. .TP
  793. \fIpathName \fBscan mark \fIx y\fR
  794. Records \fIx\fR and \fIy\fR and the canvas's current view;  used
  795. in conjunction with later \fBscan dragto\fR commands.
  796. Typically this command is associated with a mouse button press in
  797. the widget and \fIx\fR and \fIy\fR are the coordinates of the
  798. mouse.  It returns an empty string.
  799. .TP
  800. \fIpathName \fBscan dragto \fIx y\fR.
  801. This command computes the difference between its \fIx\fR and \fIy\fR
  802. arguments (which are typically mouse coordinates) and the \fIx\fR and
  803. \fIy\fR arguments to the last \fBscan mark\fR command for the widget.
  804. It then adjusts the view by 10 times the
  805. difference in coordinates.  This command is typically associated
  806. with mouse motion events in the widget, to produce the effect of
  807. dragging the canvas at high speed through its window.  The return
  808. value is an empty string.
  809. .RE
  810. .TP
  811. \fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR?
  812. Manipulates the selection in one of several ways, depending on
  813. \fIoption\fR.
  814. The command may take any of the forms described below.
  815. In all of the descriptions below, \fItagOrId\fR must refer to
  816. an item that supports indexing and selection;  if it refers to
  817. multiple items then the first of
  818. these that supports indexing and the selection is used.
  819. \fIIndex\fR gives a textual description of a position
  820. within \fItagOrId\fR, as described in INDICES above.
  821. .RS
  822. .TP
  823. \fIpathName \fBselect adjust \fItagOrId index\fR
  824. Locate the end of the selection in \fItagOrId\fR nearest
  825. to the character given by \fIindex\fR, and adjust that
  826. end of the selection to be at \fIindex\fR (i.e. including
  827. but not going beyond \fIindex\fR).
  828. The other end of the selection is made the anchor point
  829. for future \fBselect to\fR commands.
  830. If the selection isn't currently in \fItagOrId\fR then
  831. this command behaves the same as the \fBselect to\fR widget
  832. command.
  833. Returns an empty string.
  834. .TP
  835. \fIpathName \fBselect clear\fR
  836. Clear the selection if it is in this widget.
  837. If the selection isn't in this widget then the command
  838. has no effect.
  839. Returns an empty string.
  840. .TP
  841. \fIpathName \fBselect from \fItagOrId index\fR
  842. Set the selection anchor point for the widget to be just
  843. before the character
  844. given by \fIindex\fR in the item given by \fItagOrId\fR.
  845. This command doesn't change the selection;  it just sets
  846. the fixed end of the selection for future \fBselect to\fR
  847. commands.
  848. Returns an empty string.
  849. .TP
  850. \fIpathName \fBselect item\fR
  851. Returns the id of the selected item, if the selection is in an
  852. item in this canvas.
  853. If the selection is not in this canvas then an empty string
  854. is returned.
  855. .TP
  856. \fIpathName \fBselect to \fItagOrId index\fR
  857. Set the selection to consist of those characters of \fItagOrId\fR
  858. between the selection anchor point and
  859. \fIindex\fR.
  860. The new selection will include the character given by \fIindex\fR;
  861. it will include the character given by the anchor point only if
  862. \fIindex\fR is greater than or equal to the anchor point.
  863. The anchor point is determined by the most recent \fBselect adjust\fR
  864. or \fBselect from\fR command for this widget.
  865. If the selection anchor point for the widget isn't currently in
  866. \fItagOrId\fR, then it is set to the same character given
  867. by \fIindex\fR.
  868. Returns an empty string.
  869. .RE
  870. .TP
  871. \fIpathName \fBtype\fI tagOrId\fR
  872. Returns the type of the item given by \fItagOrId\fR, such as
  873. \fBrectangle\fR or \fBtext\fR.
  874. If \fItagOrId\fR refers to more than one item, then the type
  875. of the first item in the display list is returned.
  876. If \fItagOrId\fR doesn't refer to any items at all then
  877. an empty string is returned.
  878. .TP
  879. \fIpathName \fBxview\fI index\fR
  880. Change the view in the canvas so that the canvas position given by
  881. \fIindex\fR appears at the left edge of the window.
  882. This command is typically used by scrollbars to scroll the
  883. canvas.
  884. \fIIndex\fR counts in units of scroll increments (the value of the
  885. \fBscrollIncrement\fR option):  a value of 0 corresponds to the left
  886. edge of the scroll region (as defined by the \fBscrollRegion\fR
  887. option),  a value of 1 means one scroll unit to the right of this,
  888. and so on.  The return value is an empty string.
  889. .TP
  890. \fIpathName \fByview\fI index\fR
  891. Change the view in the canvas so that the canvas position given by
  892. \fIindex\fR appears at the top edge of the window.
  893. This command is typically used by scrollbars to scroll the
  894. canvas.
  895. \fIIndex\fR counts in units of scroll increments (the value of the
  896. \fBscrollIncrement\fR option):  a value of 0 corresponds to the top
  897. edge of the scroll region (as defined by the \fBscrollRegion\fR
  898. option),  a value of 1 means one scroll unit below this,
  899. and so on.  The return value is an empty string.
  900.  
  901. .SH "OVERVIEW OF ITEM TYPES"
  902. .PP
  903. The sections below describe the various types of items supported
  904. by canvas widgets.  Each item type is characterized by two things:
  905. first, the form of the \fBcreate\fR command used to create
  906. instances of the type;  and second, a set of configuration options
  907. for items of that type, which may be used in the
  908. \fBcreate\fR and \fBitemconfigure\fR widget commands.
  909. Most items don't support indexing or selection or the commands
  910. related to them, such as \fBindex\fR and \fBinsert\fR.
  911. Where items do support these facilities, it is noted explicitly
  912. in the descriptions below (at present, only text items provide
  913. this support).
  914.  
  915. .SH "ARC ITEMS"
  916. .PP
  917. .VS
  918. Items of type \fBarc\fR appear on the display as arc-shaped regions.
  919. An arc is a section of an oval delimited by two angles (specified
  920. by the \fB\-start\fR and \fB\-extent\fR options) and displayed in
  921. one of several ways (specified by the \fB\-style\fR option).
  922. Arcs are created with widget commands of the following form:
  923. .DS
  924. \fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
  925. .DE
  926. The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give
  927. the coordinates of two diagonally opposite corners of a
  928. rectangular region enclosing the oval that defines the arc.
  929. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  930. pairs, each of which sets one of the configuration options
  931. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  932. used in \fBitemconfigure\fR widget commands to change the item's
  933. configuration.
  934. The following options are supported for arcs:
  935. .TP
  936. \fB\-extent \fIdegrees\fR
  937. Specifies the size of the angular range occupied by the arc.
  938. The arc's range extends for \fIdegrees\fR degrees counter-clockwise
  939. from the starting angle given by the \fB\-start\fR option.
  940. \fIDegrees\fR may be negative.
  941. .TP
  942. \fB\-fill \fIcolor\fR
  943. Fill the region of the arc with \fIcolor\fR.
  944. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
  945. If \fIcolor\fR is an empty string (the default), then
  946. then the arc will not be filled.
  947. .TP
  948. \fB\-outline \fIcolor\fR
  949. \fIColor\fR specifies a color to use for drawing the arc's
  950. outline;  it may have any of the forms accepted by \fBTk_GetColor\fR.
  951. This option defaults to \fBblack\fR.  If the arc's style is
  952. \fBarc\fR then this option is ignored (the section of perimeter is
  953. filled using the \fB\-fill\fR option).  If \fIcolor\fR is specified
  954. as an empty string then no outline is drawn for the arc.
  955. .TP
  956. \fB\-start \fIdegrees\fR
  957. Specifies the beginning of the angular range occupied by the
  958. arc.
  959. \fIDegrees\fR is given in units of degrees measured counter-clockwise
  960. from the 3-o'clock position;  it may be either positive or negative.
  961. .TP
  962. \fB\-stipple \fIbitmap\fR
  963. Indicates that the arc should be filled in a stipple pattern;
  964. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  965. forms accepted by \fBTk_GetBitmap\fR.
  966. If the \fB\-fill\fR option hasn't been specified then this option
  967. has no effect.
  968. If \fIbitmap\fR is an empty string (the default), then filling is done
  969. in a solid fashion.
  970. .TP
  971. \fB\-style \fItype\fR
  972. Specifies how to draw the arc.  If \fItype\fR is \fBpieslice\fR
  973. (the default) then the arc's region is defined by a section
  974. of the oval's perimiter plus two line segments, one between the center
  975. of the oval and each end of the perimeter section.
  976. If \fItype\fR is \fBchord\fR then the arc's region is defined
  977. by a section of the oval's permiter plus a single line segment
  978. connecting the two end points of the perimiter section.
  979. If \fItype\fR is \fBarc\fR then the arc's region consists of
  980. a section of the perimeter alone.  In this last case there is
  981. no outline for the arc and the \fB\-outline\fR option is ignored.
  982. .TP
  983. \fB\-tags \fItagList\fR
  984. Specifies a set of tags to apply to the item.
  985. \fITagList\fR consists of a list of tag names, which replace any
  986. existing tags for the item.
  987. \fITagList\fR may be an empty list.
  988. .TP
  989. \fB\-width \fIoutlineWidth\fR
  990. Specifies the width of the outline to be drawn around
  991. the arc's region, in any of the forms described in the COORDINATES
  992. section above.
  993. If the \fB\-outline\fR option has been specified as an empty string
  994. then this option has no effect.
  995. Wide outlines will be drawn centered on the edges of the arc's region.
  996. This option defaults to 1.0.
  997.  
  998. .SH "BITMAP ITEMS"
  999. .PP
  1000. Items of type \fBbitmap\fR appear on the display as images with
  1001. two colors, foreground and background.
  1002. Bitmaps are created with widget commands of the following form:
  1003. .DS
  1004. \fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR?
  1005. .DE
  1006. The arguments \fIx\fR and \fIy\fR specify the coordinates of a
  1007. point used to position the bitmap on the display (see the \fB\-anchor\fR
  1008. option below for more information on how bitmaps are displayed).
  1009. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1010. pairs, each of which sets one of the configuration options
  1011. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1012. used in \fBitemconfigure\fR widget commands to change the item's
  1013. configuration.
  1014. The following options are supported for bitmaps:
  1015. .TP
  1016. \fB\-anchor \fIanchorPos\fR
  1017. \fIAnchorPos\fR tells how to position the bitmap relative to the
  1018. positioning point for the item;  it may have any of the forms
  1019. accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR
  1020. is \fBcenter\fR then the bitmap is centered on the point;  if
  1021. \fIanchorPos\fR is \fBn\fR then the bitmap will be drawn so that
  1022. its top center point is at the positioning point.
  1023. This option defaults to \fBcenter\fR.
  1024. .TP
  1025. \fB\-background \fIcolor\fR
  1026. Specifies a color to use for each of the bitmap pixels
  1027. whose value is 0.
  1028. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
  1029. If this option isn't specified, or if it is specified as an empty
  1030. string, then the background color for the canvas is used.
  1031. .TP
  1032. \fB\-bitmap \fIbitmap\fR
  1033. Specifies the bitmap to display in the item.
  1034. \fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR.
  1035. .TP
  1036. \fB\-foreground \fIcolor\fR
  1037. Specifies a color to use for each of the bitmap pixels
  1038. whose value is 1.
  1039. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and
  1040. defaults to \fBblack\fR.
  1041. .TP
  1042. \fB\-tags \fItagList\fR
  1043. Specifies a set of tags to apply to the item.
  1044. \fITagList\fR consists of a list of tag names, which replace any
  1045. existing tags for the item.
  1046. \fITagList\fR may be an empty list.
  1047. .VE
  1048.  
  1049. .SH "LINE ITEMS"
  1050. .PP
  1051. Items of type \fBline\fR appear on the display as one or more connected
  1052. line segments or curves.
  1053. Lines are created with widget commands of the following form:
  1054. .DS
  1055. \fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value option value ...\fR?
  1056. .DE
  1057. The arguments \fIx1\fR through \fIyn\fR give
  1058. the coordinates for a series of two or more points that describe
  1059. a series of connected line segments.
  1060. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1061. pairs, each of which sets one of the configuration options
  1062. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1063. used in \fBitemconfigure\fR widget commands to change the item's
  1064. configuration.
  1065. The following options are supported for lines:
  1066. .TP
  1067. \fB\-arrow \fIwhere\fR
  1068. Indicates whether or not arrowheads are to be drawn at one or both
  1069. ends of the line.
  1070. \fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads),
  1071. \fBfirst\fR (for an arrowhead at the first point of the line),
  1072. \fBlast\fR (for an arrowhead at the last point of the line), or
  1073. \fBboth\fR (for arrowheads at both ends).
  1074. This option defaults to \fBnone\fR.
  1075. .TP
  1076. \fB\-arrowshape \fIshape\fR
  1077. This option indicates how to draw arrowheads.
  1078. The \fIshape\fR argument must be a list with three elements, each
  1079. specifying a distance in any of the forms described in
  1080. the COORDINATES section above.
  1081. The first element of the list gives the distance along the line
  1082. from the neck of the arrowhead to its tip.
  1083. The second element gives the distance along the line from the
  1084. trailing points of the arrowhead to the tip, and the third
  1085. element gives the distance from the outside edge of the line to the
  1086. trailing points.
  1087. If this option isn't specified then Tk picks a ``reasonable'' shape.
  1088. .TP
  1089. \fB\-capstyle \fIstyle\fR
  1090. Specifies the ways in which caps are to be drawn at the endpoints
  1091. of the line.
  1092. \fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR
  1093. (\fBbutt\fR, \fBprojecting\fR, or \fBround\fR).
  1094. If this option isn't specified then it defaults to \fBbutt\fR.
  1095. Where arrowheads are drawn the cap style is ignored.
  1096. .TP
  1097. \fB\-fill \fIcolor\fR
  1098. \fIColor\fR specifies a color to use for drawing the line; it may have
  1099. any of the forms acceptable to \fBTk_GetColor\fR.  It may also be an
  1100. empty string, in which case the line will be transparent.
  1101. This option defaults to \fBblack\fR.
  1102. .TP
  1103. \fB\-joinstyle \fIstyle\fR
  1104. Specifies the ways in which joints are to be drawn at the vertices
  1105. of the line.
  1106. \fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR
  1107. (\fBbevel\fR, \fBmiter\fR, or \fBround\fR).
  1108. If this option isn't specified then it defaults to \fBmiter\fR.
  1109. If the line only contains two points then this option is
  1110. irrelevant.
  1111. .TP
  1112. \fB\-smooth \fIboolean\fR
  1113. .VS
  1114. \fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR.
  1115. It indicates whether or not the line should be drawn as a curve.
  1116. If so, the line is rendered as a set of Bezier splines: one spline
  1117. is drawn for the first and second line segments, one for the second
  1118. and third, and so on.  Straight-line segments can be generated within
  1119. a curve by duplicating the end-points of the desired line segment.
  1120. .TP
  1121. \fB\-splinesteps \fInumber\fR
  1122. Specifies the degree of smoothness desired for curves:  each spline
  1123. will be approximated with \fInumber\fR line segments.  This
  1124. option is ignored unless the \fB\-smooth\fR option is true.
  1125. .VE
  1126. .TP
  1127. \fB\-stipple \fIbitmap\fR
  1128. Indicates that the line should be filled in a stipple pattern;
  1129. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  1130. forms accepted by \fBTk_GetBitmap\fR.
  1131. If \fIbitmap\fR is an empty string (the default), then filling is
  1132. done in a solid fashion.
  1133. .TP
  1134. \fB\-tags \fItagList\fR
  1135. .VS
  1136. Specifies a set of tags to apply to the item.
  1137. \fITagList\fR consists of a list of tag names, which replace any
  1138. existing tags for the item.
  1139. \fITagList\fR may be an empty list.
  1140. .VE
  1141. .TP
  1142. \fB\-width \fIlineWidth\fR
  1143. \fILineWidth\fR specifies the width of the line, in any of the forms
  1144. described in the COORDINATES section above.
  1145. Wide lines will be drawn centered on the path specified by the
  1146. points.
  1147. If this option isn't specified then it defaults to 1.0.
  1148.  
  1149. .SH "OVAL ITEMS"
  1150. .PP
  1151. Items of type \fBoval\fR appear as circular or oval regions on
  1152. the display.  Each oval may have an outline, a fill, or
  1153. both.  Ovals are created with widget commands of the
  1154. following form:
  1155. .DS
  1156. \fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
  1157. .DE
  1158. The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give
  1159. the coordinates of two diagonally opposite corners of a
  1160. rectangular region enclosing the oval.
  1161. The oval will touch this enclosing region at its top,
  1162. bottom, left, and right edges.
  1163. If the region is square then the resulting oval is circular;
  1164. othwerwise it is elongated in shape.
  1165. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1166. pairs, each of which sets one of the configuration options
  1167. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1168. used in \fBitemconfigure\fR widget commands to change the item's
  1169. configuration.
  1170. The following options are supported for ovals:
  1171. .TP
  1172. \fB\-fill \fIcolor\fR
  1173. Fill the area of the oval with \fIcolor\fR.
  1174. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
  1175. If \fIcolor\fR is an empty string (the default), then
  1176. then the oval will not be filled.
  1177. .TP
  1178. \fB\-outline \fIcolor\fR
  1179. \fIColor\fR specifies a color to use for drawing the oval's
  1180. outline;  it may have any of the forms accepted by \fBTk_GetColor\fR.
  1181. This option defaults to \fBblack\fR.
  1182. If \fIcolor\fR is an empty string then no outline will be
  1183. drawn for the oval.
  1184. .TP
  1185. \fB\-stipple \fIbitmap\fR
  1186. Indicates that the oval should be filled in a stipple pattern;
  1187. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  1188. forms accepted by \fBTk_GetBitmap\fR.
  1189. If the \fB\-fill\fR option hasn't been specified then this option
  1190. has no effect.
  1191. If \fIbitmap\fR is an empty string (the default), then filling is done
  1192. in a solid fashion.
  1193. .TP
  1194. \fB\-tags \fItagList\fR
  1195. .VS
  1196. Specifies a set of tags to apply to the item.
  1197. \fITagList\fR consists of a list of tag names, which replace any
  1198. existing tags for the item.
  1199. \fITagList\fR may be an empty list.
  1200. .VE
  1201. .TP
  1202. \fB\-width \fIoutlineWidth\fR
  1203. \fIoutlineWidth\fR specifies the width of the outline to be drawn around
  1204. the oval, in any of the forms described in the COORDINATES section above.
  1205. If the \fB\-outline\fR option hasn't been specified then this option
  1206. has no effect.
  1207. .VS
  1208. Wide outlines are drawn centered on the oval path defined by
  1209. \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
  1210. .VE
  1211. This option defaults to 1.0.
  1212.  
  1213. .SH "POLYGON ITEMS"
  1214. .PP
  1215. Items of type \fBpolygon\fR appear as polygonal or curved filled regions
  1216. on the display.
  1217. Polygons are created with widget commands of the following form:
  1218. .DS
  1219. \fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value option value ...\fR?
  1220. .DE
  1221. The arguments \fIx1\fR through \fIyn\fR specify the coordinates for
  1222. three or more points that define a closed polygon.
  1223. The first and last points may be the same;  whether they are or not,
  1224. Tk will draw the polygon as a closed polygon.
  1225. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1226. pairs, each of which sets one of the configuration options
  1227. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1228. used in \fBitemconfigure\fR widget commands to change the item's
  1229. configuration.
  1230. The following options are supported for polygons:
  1231. .TP
  1232. \fB\-fill \fIcolor\fR
  1233. \fIColor\fR specifies a color to use for filling the area of the
  1234. polygon; it may have any of the forms acceptable to \fBTk_GetColor\fR.
  1235. If \fIcolor\fR is an empty string then the polygon will be
  1236. transparent.
  1237. This option defaults to \fBblack\fR.
  1238. .TP
  1239. \fB\-smooth \fIboolean\fR
  1240. .VS
  1241. \fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR
  1242. It indicates whether or not the polygon should be drawn with a
  1243. curved perimeter.
  1244. If so, the outline of the polygon becomes a set of Bezier splines,
  1245. one spline for the first and second line segments, one for the second
  1246. and third, and so on.  Straight-line segments can be generated in a
  1247. smoothed polygon by duplicating the end-points of the desired line segment.
  1248. .TP
  1249. \fB\-splinesteps \fInumber\fR
  1250. Specifies the degree of smoothness desired for curves:  each spline
  1251. will be approximated with \fInumber\fR line segments.  This
  1252. option is ignored unless the \fB\-smooth\fR option is true.
  1253. .VE
  1254. .TP
  1255. \fB\-stipple \fIbitmap\fR
  1256. Indicates that the polygon should be filled in a stipple pattern;
  1257. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  1258. forms accepted by \fBTk_GetBitmap\fR.
  1259. If \fIbitmap\fR is an empty string (the default), then filling is
  1260. done in a solid fashion.
  1261. .TP
  1262. \fB\-tags \fItagList\fR
  1263. .VS
  1264. Specifies a set of tags to apply to the item.
  1265. \fITagList\fR consists of a list of tag names, which replace any
  1266. existing tags for the item.
  1267. \fITagList\fR may be an empty list.
  1268. .VE
  1269.  
  1270. .SH "RECTANGLE ITEMS"
  1271. .PP
  1272. Items of type \fBrectangle\fR appear as rectangular regions on
  1273. the display.  Each rectangle may have an outline, a fill, or
  1274. both.  Rectangles are created with widget commands of the
  1275. following form:
  1276. .DS
  1277. \fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
  1278. .DE
  1279. The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give
  1280. the coordinates of two diagonally opposite corners of the rectangle.
  1281. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1282. pairs, each of which sets one of the configuration options
  1283. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1284. used in \fBitemconfigure\fR widget commands to change the item's
  1285. configuration.
  1286. The following options are supported for rectangles:
  1287. .TP
  1288. \fB\-fill \fIcolor\fR
  1289. Fill the area of the rectangle with \fIcolor\fR, which may be
  1290. specified in any of the forms accepted by \fBTk_GetColor\fR.
  1291. If \fIcolor\fR is an empty string (the default), then
  1292. then the rectangle will not be filled.
  1293. .TP
  1294. \fB\-outline \fIcolor\fR
  1295. Draw an outline around the edge of the rectangle in \fIcolor\fR.
  1296. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
  1297. This option defaults to \fBblack\fR.
  1298. If \fIcolor\fR is an empty string then no outline will be
  1299. drawn for the rectangle.
  1300. .TP
  1301. \fB\-stipple \fIbitmap\fR
  1302. Indicates that the rectangle should be filled in a stipple pattern;
  1303. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  1304. forms accepted by \fBTk_GetBitmap\fR.
  1305. If the \fB\-fill\fR option hasn't been specified then this option
  1306. has no effect.
  1307. If \fIbitmap\fR is an empty string (the default), then filling
  1308. is done in a solid fashion.
  1309. .TP
  1310. \fB\-tags \fItagList\fR
  1311. .VS
  1312. Specifies a set of tags to apply to the item.
  1313. \fITagList\fR consists of a list of tag names, which replace any
  1314. existing tags for the item.
  1315. \fITagList\fR may be an empty list.
  1316. .VE
  1317. .TP
  1318. \fB\-width \fIoutlineWidth\fR
  1319. \fIOutlineWidth\fR specifies the width of the outline to be drawn around
  1320. the rectangle, in any of the forms described in the COORDINATES section above.
  1321. If the \fB\-outline\fR option hasn't been specified then this option
  1322. has no effect.
  1323. .VS
  1324. Wide outlines are drawn centered on the rectangular path
  1325. defined by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
  1326. .VE
  1327. This option defaults to 1.0.
  1328.  
  1329. .SH "TEXT ITEMS"
  1330. .PP
  1331. A text item displays a string of characters on the screen in one
  1332. or more lines.
  1333. Text items support indexing and selection, along with the
  1334. following text-related canvas widget commands:  \fBcursor\fR,
  1335. \fBdchars\fR, \fBfocus\fR, \fBindex\fR, \fBinsert\fR,
  1336. \fBselect\fR.
  1337. Text items are created with widget commands of the following
  1338. form:
  1339. .DS
  1340. \fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR?
  1341. .DE
  1342. The arguments \fIx\fR and \fIy\fR specify the coordinates of a
  1343. point used to position the text on the display (see the options
  1344. below for more information on how text is displayed).
  1345. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1346. pairs, each of which sets one of the configuration options
  1347. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1348. used in \fBitemconfigure\fR widget commands to change the item's
  1349. configuration.
  1350. The following options are supported for text items:
  1351. .TP
  1352. \fB\-anchor \fIanchorPos\fR
  1353. \fIAnchorPos\fR tells how to position the text relative to the
  1354. positioning point for the text;  it may have any of the forms
  1355. accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR
  1356. is \fBcenter\fR then the text is centered on the point;  if
  1357. \fIanchorPos\fR is \fBn\fR then the text will be drawn such that
  1358. the top center point of the rectangular region occupied by the
  1359. text will be at the positioning point.
  1360. This option defaults to \fBcenter\fR.
  1361. .TP
  1362. \fB\-fill \fIcolor\fR
  1363. \fIColor\fR specifies a color to use for filling the text characters;
  1364. it may have any of the forms accepted by \fBTk_GetColor\fR.
  1365. If this option isn't specified then it defaults to \fBblack\fR.
  1366. .TP
  1367. \fB\-font \fIfontName\fR
  1368. Specifies the font to use for the text item.
  1369. \fIFontName\fR may be any string acceptable to \fBTk_GetFontStruct\fR.
  1370. If this option isn't specified, it defaults to a system-dependent
  1371. font.
  1372. .TP
  1373. \fB\-justify \fIhow\fR
  1374. Specifies how to justify the text within its bounding region.
  1375. \fIHow\fR must be one of the values \fBleft\fR, \fBright\fR,
  1376. or \fBcenter\fR.
  1377. This option will only matter if the text is displayed as multiple
  1378. lines.
  1379. If the option is omitted, it defaults to \fBleft\fR.
  1380. .TP
  1381. \fB\-stipple \fIbitmap\fR
  1382. Indicates that the text should be drawn in a stippled pattern
  1383. rather than solid;
  1384. \fIbitmap\fR specifies the stipple pattern to use, in any of the
  1385. forms accepted by \fBTk_GetBitmap\fR.
  1386. If \fIbitmap\fR is an empty string (the default) then the text
  1387. is drawn in a solid fashion.
  1388. .TP
  1389. \fB\-tags \fItagList\fR
  1390. .VS
  1391. Specifies a set of tags to apply to the item.
  1392. \fITagList\fR consists of a list of tag names, which replace any
  1393. existing tags for the item.
  1394. \fITagList\fR may be an empty list.
  1395. .VE
  1396. .TP
  1397. \fB\-text \fIstring\fR
  1398. \fIString\fR specifies the characters to be displayed in the text item.
  1399. Newline characters cause line breaks.
  1400. The characters in the item may also be changed with the
  1401. \fBinsert\fR and \fBdelete\fR widget commands.
  1402. This option defaults to an empty string.
  1403. .TP
  1404. \fB\-width \fIlineLength\fR
  1405. Specifies a maximum line length for the text, in any of the forms
  1406. described in the COORDINATES section abov.
  1407. If this option is zero (the default) the text is broken into
  1408. lines only at newline characters.
  1409. However, if this option is non-zero then any line that would
  1410. be longer than \fIlineLength\fR is broken just before a space
  1411. character to make the line shorter than \fIlineLength\fR;  the
  1412. space character is treated as if it were a newline
  1413. character.
  1414.  
  1415. .SH "WINDOW ITEMS"
  1416. .PP
  1417. .VS
  1418. Items of type \fBwindow\fR cause a particular window to be displayed
  1419. at a given position on the canvas.
  1420. Window items are created with widget commands of the following form:
  1421. .DS
  1422. \fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR?
  1423. .DE
  1424. The arguments \fIx\fR and \fIy\fR specify the coordinates of a
  1425. point used to position the window on the display (see the \fB\-anchor\fR
  1426. option below for more information on how bitmaps are displayed).
  1427. After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR
  1428. pairs, each of which sets one of the configuration options
  1429. for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
  1430. used in \fBitemconfigure\fR widget commands to change the item's
  1431. configuration.
  1432. The following options are supported for window items:
  1433. .TP
  1434. \fB\-anchor \fIanchorPos\fR
  1435. \fIAnchorPos\fR tells how to position the window relative to the
  1436. positioning point for the item;  it may have any of the forms
  1437. accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR
  1438. is \fBcenter\fR then the window is centered on the point;  if
  1439. \fIanchorPos\fR is \fBn\fR then the window will be drawn so that
  1440. its top center point is at the positioning point.
  1441. This option defaults to \fBcenter\fR.
  1442. .TP
  1443. \fB\-height \fIpixels\fR
  1444. Specifies the height to assign to the item's window.
  1445. \fIPixels\fR may have any of the
  1446. forms described in the COORDINATES section above.
  1447. If this option isn't specified, or if it is specified as an empty
  1448. string, then the window is given whatever height it requests internally.
  1449. .TP
  1450. \fB\-tags \fItagList\fR
  1451. Specifies a set of tags to apply to the item.
  1452. \fITagList\fR consists of a list of tag names, which replace any
  1453. existing tags for the item.
  1454. \fITagList\fR may be an empty list.
  1455. .TP
  1456. \fB\-width \fIpixels\fR
  1457. Specifies the width to assign to the item's window.
  1458. \fIPixels\fR may have any of the
  1459. forms described in the COORDINATES section above.
  1460. If this option isn't specified, or if it is specified as an empty
  1461. string, then the window is given whatever width it requests internally.
  1462. .TP
  1463. \fB\-window \fIpathName\fR
  1464. Specifies the window to associate with this item.
  1465. The window specified by \fIpathName\fR must either be a child of
  1466. the canvas widget or a child of some ancestor of the canvas widget.
  1467. \fIPathName\fR may not refer to a top-level window.
  1468. .VE
  1469.  
  1470. .SH "APPLICATION-DEFINED ITEM TYPES"
  1471. .PP
  1472. It is possible for individual applications to define new item
  1473. types for canvas widgets using C code.
  1474. The interfaces for this mechanism are not presently documented,
  1475. and it's possible they may change, but you should be able to
  1476. see how they work by examining the code for some of the existing
  1477. item types.
  1478.  
  1479. .SH BINDINGS
  1480. .PP
  1481. In the current implementation, new canvases are not given any
  1482. default behavior:  you'll have to execute explicit Tcl commands
  1483. to give the canvas its behavior.
  1484.  
  1485. .SH CREDITS
  1486. .PP
  1487. Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
  1488. \fIezd\fR program.  \fIEzd\fR provides structured graphics in a Scheme
  1489. environment and preceded canvases by a year or two.  Its simple
  1490. mechanisms for placing and animating graphical objects inspired the
  1491. functions of canvases.
  1492.  
  1493. .SH KEYWORDS
  1494. canvas, widget
  1495.